3D Graphics Programming with QuickDraw 3D 1.5.4

Creating Storage Pixmaps

The data passed to the Q3PixmapTexture_New function (as in Listing 7 ) is a storage pixmap, of type TQ3StoragePixmap . The image field of a storage pixmap specifies a storage object that contains the pixmap data to be applied as a texture. You can call either Q3MemoryStorage_New or Q3MemoryStorage_NewBuffer to create a storage object. Which function you use depends on whether (1) you want QuickDraw 3D to maintain the image data in an internal buffer or (2) you want to maintain the data in your own buffer.

To let QuickDraw 3D manage the pixmap data, you can assign the image field of a storage pixmap using code like this:



 
myStoragePixmap.image = Q3MemoryStorage_New(myBuffer, mySize);

This code asks QuickDraw 3D to allocate a buffer internally, of the specified size. Once Q3MemoryStorage_New returns successfully, you can dispose of the buffer myBuffer , because QuickDraw 3D has copied the texture pixmap data into its own internal memory.

If you prefer, you can maintain the pixmap data in your application's memory partition and avoid the overhead of having the data copied to internal QuickDraw 3D memory. (This is especially useful if you want to animate a texture by changing the texture pixmap data from frame to frame.) To do this, you create a storage object by calling the Q3MemoryStorage_NewBuffer function, like this:



 
myStoragePixmap.image = Q3MemoryStorage_NewBuffer

                                            (myBuffer, mySize, mySize);

In this case, you should not dispose of the data buffer. You can change the pixmap data by calling Q3MemoryStorage_SetBuffer .



 
Q3MemoryStorage_SetBuffer

                (myStoragePixmap.image, myBuffer, mySize, mySize);

You need to call Q3MemoryStorage_SetBuffer to force QuickDraw 3D to update any caches.

You can also change the data of a storage object created by a call to Q3MemoryStorage_New , by calling Q3MemoryStorage_Set .